Review: Agentic Development

Must fix

• Incorrect skill count (19 published skills, not 17): The source section comment says "all 17 published skills" and the "Available skills" heading states "The following skills are published in the dfinity/icskills registry" then lists 17. But .sources/icskills/skills/ contains 19 actual skills — canhelp and custom-domains are missing from the table. These are both fully published skills with SKILL.md files:

  • canhelp — "Display a human-readable summary of a canister's interface given its mainnet canister ID or a human-readable name."
  • custom-domains — "Register and manage custom domains for IC canisters via the HTTP gateway custom domain service."
    Fix: either add both missing skills to the table, or if intentionally omitting action-skills like canhelp, at least add custom-domains (which is a standard integration skill) and update the count to match.

• Wrong domain in curl examples: The "Agent-friendly documentation" section uses https://developer.internetcomputer.org/ in both curl examples:

  curl -sL https://developer.internetcomputer.org/llms.txt
  curl -sL https://developer.internetcomputer.org/guides/tools/agentic-development.md
  

  The current astro.config.mjs sets site: "https://beta-docs.internetcomputer.org" and the built dist/llms.txt uses beta-docs.internetcomputer.org. No other page in the docs uses developer.internetcomputer.org. These examples will point readers to a non-existent domain. Fix: use the actual configured domain (beta-docs.internetcomputer.org) or use a placeholder like <your-docs-domain> with a note that the canonical URL will be updated at launch.

Suggestions

• canhelp is an action skill, not an integration skill — if the intent is to list only "integration pattern" skills (not action/tool skills), the introductory sentence could clarify this: "The following integration skills are published..." and note that additional tool skills like canhelp are available at the registry. This prevents the table from being seen as exhaustive when it isn't.

• Windsurf path may be outdated: The page says Windsurf installs skills to .windsurf/rules/. The icskills source (constants.ts) describes Windsurf's integration as "Cascade context", not "Rules files". Cursor uses "Rules files". These two are architecturally different — Windsurf's Cascade context is not just a rules directory. This claim is not sourced from the icskills repository; it appears to come from training data. Consider softening to "installed into your Windsurf project" without specifying the path, or verify against the npx skills add CLI output.

• GitHub Copilot path not verifiable from source: The page claims skills go to .github/copilot-instructions.md. This specific path is not documented in the icskills source. Since the npx skills add CLI handles placement automatically, emphasizing the exact path may introduce a maintenance burden if the Copilot integration changes. Consider noting that the CLI handles installation and the exact path depends on the Copilot version.

• "When to load which skill" table is missing custom-domains: If you add custom-domains to the skills table (see Must fix above), consider adding a row to the "When to load which skill" table: "Frontend dApp with custom domain" → icp-cli, asset-canister, custom-domains.

• Opening sentence references icp-cli skill files alongside icp CLI: The opening says "the same tools as human developers: icp for project management, icp-cli skill files for implementation patterns". This conflates the CLI tool (icp) with the skill named icp-cli. A developer reading this could misread icp-cli as a command. Suggest: "...icp for project management, icskills for implementation patterns, and the llms.txt discovery endpoint...".

Verified

• All three internal links resolve to existing files: overview.md, ../../getting-started/quickstart.md, migrating-from-dfx.md.
• npx skills add dfinity/icskills install command verified against .sources/icskills/README.md.
• Programmatic access URL table verified against .sources/icskills/README.md — all five URL patterns match.
• curl -sL https://skills.internetcomputer.org/.well-known/skills/icp-cli/SKILL.md manual install command format verified against README.
• All 17 listed skill descriptions cross-checked against .sources/icskills/skills/*/SKILL.md frontmatter — no factual inaccuracies found in descriptions for the 17 listed skills.
• No dfx tool references (the link text "Migrating from dfx" matches the actual target page title and is acceptable).
• No mo:base imports, no .mdx file (correct .md format), no internetcomputer.org/docs/ links.
• <!-- Upstream: informed by dfinity/icskills — README.md, skills/*/SKILL.md --> comment present at end of file.
• Frontmatter is complete: title, description, and sidebar.order all present.
• Agent Skills Discovery RFC link (github.com/cloudflare/agent-skills-discovery-rfc) verified against .sources/icskills/README.md.
• Content brief fully covered: what icskills are, installing, configuring agents, skills vs docs relationship.
• Page structure follows orient → explain → instruct → next steps. No content buried or out of order.
• Code snippets have no Motoko or Rust code (not applicable to this page topic). CLI snippets are bash-formatted correctly.

Feedback addressed for PR #77 (docs/guides/tools/agentic-development.md):

Changes applied

Must-fix items:

• Added missing custom-domains and canhelp skills: The .sources/icskills/skills/ directory contains 19 skills; the page listed only 17. Added custom-domains to the integration skills table with a description sourced from its SKILL.md frontmatter. Added a note after the table explaining that canhelp is a tool skill (not an integration skill), with a brief description and a link to the full registry. The introductory sentence for the table now reads "The following integration skills are published..." to make the distinction clear.

• Fixed curl example domain: Both curl examples used https://developer.internetcomputer.org/ which does not exist. Changed to https://beta-docs.internetcomputer.org/ which matches the site: field in astro.config.mjs and the built dist/llms.txt output.

Suggestions applied:

• Fixed opening sentence conflating icp CLI and icp-cli skill name: Changed `icp-cli` skill files for implementation patterns to icskills for implementation patterns to avoid readers misreading the skill name as a CLI command.

• Softened Windsurf path claim: The icskills constants.ts describes Windsurf's integration as "Cascade context", not "Rules files". Removed the claim that skills go to .windsurf/rules/ and replaced with "into Windsurf's Cascade context. The CLI handles placement automatically when you select your agent during installation."

• Softened GitHub Copilot path claim: The exact .github/copilot-instructions.md path is not documented in the icskills source. Updated the section to state the CLI installs skills automatically and that the exact path depends on the Copilot version.

• Added custom-domains to "When to load which skill" table: Added "Frontend dApp with custom domain" row with icp-cli, asset-canister, custom-domains.

Items skipped

None. All feedback items were either factually correct (cross-checked against .sources/icskills/) or reasonable improvements supported by the source material.

Build note

The build fails in this worktree due to the examples submodule not being initialized (SSH blocked submodule init for that repo). This failure (remark-snippet: file not found in https-outcalls.mdx) is pre-existing and unrelated to these changes — confirmed by running the build before and after stash. The agentic-development.md page itself has no build errors.